## 聊天室

### 创建聊天室

```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "Content-Type: application/json" \
  -d '{"name":"My First Chatroom"}' \
  https://{{host}}/1.2/rtm/chatrooms
```
对话的字段可参考即时通讯总览里面的 [对话](realtime_v2.html#对话（Conversation）)。

返回
```
{"objectId"=>"5a5d7432c3422b31ed845e75", "createdAt"=>"2018-01-16T03:40:32.814Z"}
```

### 查询聊天室

```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -G \
  --data-urlencode 'where={"name": "chatroom"}' \
  --data-urlencode 'skip=1' \
  --data-urlencode 'limit=20' \
  https://{{host}}/1.2/rtm/chatrooms
```

参数 | 约束 | 说明
---|---|---
skip | 可选 |
limit | 可选 | 与 skip 联合使用实现分页
where | 可选 | 参考 [数据存储 - 查询](rest_api.html#查询)。


返回
```
{"results"=>[{"name"=>"My First Chatroom", "createdAt"=>"2018-01-17T04:15:33.386Z", "updatedAt"=>"2018-01-17T04:15:33.386Z", "objectId"=>"5a5ecde6c3422b738c8779d7"}]}
```

### 更新聊天室

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Chatroom"}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}
```

返回
```
{"updatedAt"=>"2018-01-16T03:40:37.683Z", "objectId"=>"5a5d7433c3422b31ed845e76"}
```


### 删除聊天室

```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}
```

返回
```
{}
```

### 随机获取在线成员

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/members
```

返回
```
{"result": ["clientid1", "clientid2", "clientid3"]}
```

### 查询在线成员数

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/members/online-count
```

返回

```
{"result": 3}
```


### 发消息

该接口要求使用 master key。

```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "message": ""}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages
```
**注意**，由于这个接口的管理性质，当你通过这个接口发送消息时，我们不会检查 **from_client** 是否有权限给这个聊天室发送消息，而是统统放行，请谨慎使用这个接口。
如果你在应用中使用了我们内部定义的 [富媒体消息格式](./realtime_v2.html#消息（Message）)，在发送消息时 **message** 字段需要遵守一定的格式要求，[富媒体消息格式说明](./realtime_rest_api.html#富媒体消息格式说明) 中有详细说明。此外，聊天室目前**不支持**将消息同步发送给在线的 **from_client**。


参数 | 约束 | 说明
---|---|---
from_client | 必填 |消息的发件人 client Id
message | 必填 | 消息内容（这里的消息内容的本质是字符串，但是我们对字符串内部的格式没有做限定，<br/>理论上开发者可以随意发送任意格式，只要大小不超过 5 KB 限制即可。）
transient | 可选|是否为暂态消息，默认 false
priority | 可选 | 定义消息优先级，可选值为 high、normal、low，分别对应高、中、低三种优先级。该参数大小写不敏感，默认为高优先级 high。本参数仅对暂态消息或聊天室的消息有效，高优先级下在服务端与用户设备的连接拥塞时依然排队。

返回说明：

默认情况下发送消息 API 使用异步的方式，调用后返回消息 id 和接收消息的服务器时间戳，例如 `{"msg-id":"qNkRkFWOeSqP65S9fDyHJw", "timestamp":1495431811151}`。

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 查询历史消息

该接口要求使用 master key。
为了保证获取聊天记录的安全性，可以开启签名认证，具体可以参考总览里面的 [安全与签名](realtime-guide-senior.html#安全与签名)。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/messages
```

参数 | 约束 | 说明
--- | --- | ---
msgid | 可选 | 起始的消息 id，**使用时必须加上对应消息的时间戳 timestamp 参数，作为查询的起点**
timestamp | 可选 | 查询起始的时间戳。默认是当前时间，单位是毫秒
till_msgid | 可选 | 查询终止的消息 id。**使用时必须加上消息的时间戳 till_timestamp 参数，作为查询的终点**
till_timestamp | 可选 | 查询终止的时间戳，默认为 0，单位是毫秒
include_start | 可选 | 是否包含由 timestamp 与 msgid 确定的起始消息。布尔值，默认为 false
include_stop | 可选 | 是否包含由 till_timestamp 与 till_msgid 确定的终止消息。布尔值，默认为 false
reversed | 可选 | 以默认排序（默认按时间降序）相反的方向返回结果，这时 till_timestamp 默认为当前时间戳，timestamp 默认为 0。布尔值，默认为 false
limit | 可选 | 返回条数限制，可选，默认 100 条，最大 1000 条
client_id | 可选 | 查看者 id（签名参数）
nonce | 可选 | 签名随机字符串（签名参数）
signature_ts | 可选 | 签名时间戳（签名参数），单位是毫秒
signature | 可选 | 签名（签名参数）

本接口时间参数较多，这里举一示例供大家参考。比如某对话内有三条消息，id 分别为 id1、id2、id3，发消息的时间分别是 t1、t2、t3（t1 < t2 < t3），下面列举出不同参数组合的查询结果（空白表示使用默认值）：

| timestamp| msgid| till_timestamp| till_msgid| include_start| include_stop| reversed| 结果 |
| ---------|---------|---------|---------|---------|---------|---------|--------- |
| t3| id3| t1| id1| | | | id2 |
| t3| id3| t1| id1| true| | | id3 id2 |
| t3| id3| t1| id1| | true| | id2 id1 |
| t1| id1| t3| id3| | | true| id2 |
| t1| id1| t3| id3| true| | true| id1 id2 |
| t1| id1| t3| id3| | true| true| id2 id3 |

返回数据格式，JSON 数组，默认按消息记录从新到旧排序，设置请求参数 `reversed` 后以相反的方向排序。

返回：

```json
[
  {
    "timestamp": 1408008498571,
    "conv-id":   "219946ef32e40c515d33ae6975a5c593",
    "data":      "今天天气不错！",
    "from":      "u111872755_9d0461adf9c267ae263b3742c60fa",
    "msg-id":    "vdkGm4dtRNmhQ5gqUTFBiA",
    "is-conv":   true,
    "is-room":   false,
    "to":        "5541c02ce4b0f83f4d44414e",
    "bin":       false,
    "from-ip":   "202.117.15.217"
  },
  ...
]
```

### 修改消息

该接口要求使用 master key。
从 Objective-C SDK v6.0.0、Android SDK v4.4.0、JavaScript SDK v3.5.0 开始，我们支持了新的修改与撤回消息功能。修改或撤回消息后，即使已经收到并已缓存在客户端的消息也会被修改或撤回。对于老版本的 SDK，仅能修改或撤回服务器端的消息记录，并不能修改或撤回客户端已缓存的消息记录。

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "message": "", "timestamp": 123}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages/{message_id}
```

参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
message | 必填 | 消息体
timestamp | 必填 | 消息的时间戳

返回：
```
{"result": {}}
```

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 撤回消息

该接口要求使用 master key。需要相应 SDK 的支持，具体可参考上面的「修改消息」接口。

```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"from_client": "", "timestamp": 123}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages/{message_id}/recall
```


参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
timestamp | 必填 | 消息的时间戳


返回：
```
{"result": {}}
```

频率限制：

此接口受频率限制，[点击查看详情](#接口请求频率限制)。

### 删除消息

该接口要求使用 master key。
```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -G \
  --data-urlencode 'from_client=some-client-id' \
  --data-urlencode 'timestamp=123' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/messages/{message_id}
```

> NOTE：该接口仅删除服务端的消息，对客户端无影响。

参数 | 约束 | 说明
---|---|---
from_client | 必填 | 消息的发件人 client ID
timestamp | 必填 | 消息的时间戳


返回：
```
{}
```

### 增加临时性禁言用户

该接口要求使用 master key。
```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "some-client-id", "ttl": 50}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/temporary-silenceds
```

参数 | 说明
--- | ---
client_id | 要禁言的 id，字符串
ttl | 禁言的时间，秒数，最长 24 小时

返回

```
{}
```

### 移除临时性禁言用户

该接口要求使用 master key。
```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -G \
  --data-urlencode 'client_id=some-client-id' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/temporary-silenceds
```

返回

```
{}
```

### 对话权限

该功能介绍可参考总览里面的 [权限管理与黑名单](realtime-guide-senior.html#权限管理与黑名单)。

#### 增加权限

该接口要求使用 master key。
每个聊天室最多允许添加 10,000 个永久性禁言用户。
```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "client", "role": "role"}' \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos
```

参数 | 说明
--- | ---
clientId | 用户 ID，字符串
role | 角色，可选值 Member、Manager、Owner

返回
```
{"updatedAt"=>"2018-01-16T03:40:37.683Z", "objectId"=>"5a5d7433c3422b31ed845e76"}
```

#### 删除权限

该接口要求使用 master key。
```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos/{info-id}
```

参数 | 说明
--- | ---
info-id | 该记录对应的 objectId

返回
```
{}
```

#### 更新权限

该接口要求使用 master key。
```sh
curl -X PUT \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "client", "role": "role"}' \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos/{info-id}
```

参数 | 说明
--- | ---
client_id | 要禁言的 id，字符串。可选
role | 角色，可选值 Member、Manager、Owner。可选
info-id | 该记录对应的 objectId

返回
```
{"updatedAt"=>"2018-01-16T03:40:37.683Z", "objectId"=>"5a5d7433c3422b31ed845e76"}
```


#### 查询权限

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -G \
  --data-urlencode 'skip=1' \
  --data-urlencode 'limit=20' \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/member-infos
```

参数 | 说明
--- | ---
skip |
limit | 与 skip 联合使用实现分页
role | 本次查询只希望包含该角色

返回
```
{"results": [{"clientId"=>"client1", "objectId"=>"5a5d7433c3422b31ed845e76", "role": "Manager"}]}
```


#### 增加永久性禁言用户

该接口要求使用 master key。
每个对话最多允许添加 500 个永久性禁言用户。
```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/permanent-silenceds
```

参数 | 说明
--- | ---
client_ids | 要禁言的 Client ID 列表，数组

返回

```
{}
```

#### 移除永久性禁言用户

该接口要求使用 master key。
```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/permanent-silenceds
```

返回

```
{}
```

#### 查询永久性禁言列表

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -G \
  --data-urlencode 'limit=20' \
  https://{{host}}/1.2/rtm/chatrooms/{conv_id}/permanent-silenceds
```

参数 | 约束 | 说明
---|---|---
limit | 可选 | 与 next 联合使用实现分页，默认 10
next | 可选 | 第一次查询时返回，后面的查询带着这个参数，实现分页查询

返回

```
{"client_ids": ["client1", "client2"]}
```


### 黑名单

该功能介绍可参考总览里面的 [黑名单](realtime-guide-senior.html#黑名单)。


#### 增加聊天室黑名单

该接口要求使用 master key。该功能介绍可参考总览里面的 [黑名单](realtime-guide-senior.html#黑名单)。

加入黑名单的 client 不允许再加入该聊天室，如果之前在该聊天室中将被移除。每个聊天室最多允许添加 10,000 个黑名单。
```sh
curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -H "Content-Type: application/json" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/blacklists
```

参数 | 说明
--- | ---
client_ids | 要拉黑的 Client ID 列表，数组

返回

```
{}
```

#### 移除聊天室黑名单

该接口要求使用 master key。
```sh
curl -X DELETE \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/blacklists
```

返回

```
{}
```

#### 查询聊天室黑名单

该接口要求使用 master key。
```sh
curl -X GET \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{masterkey}},master" \
  -d '{"client_ids": ["client1", "client2"]}' \
  https://{{host}}/1.2/rtm/chatrooms/{chatroom_id}/blacklists
```

参数 | 约束 | 说明
---|---|---
limit | 可选 | 与 next 联合使用实现分页，默认 10
next | 可选 | 第一次查询时返回，后面的查询带着这个参数，实现分页查询

返回

```
{"client_ids": ["client1", "client2"]}
```
